MQTT Client SL Library Documentation¶

Description [1]¶

MQTT (Message Queuing Telemetry Transport) is an open-source IoT protocol that allows for the transmission of telemetry data as messages between devices. Device communication always takes place by means of an MQTT broker (e.g. Mosquitto https://mosquitto.org/). Messages are sent and subscribed to based on topics. A topic corresponds to a path (e.g. device1/temperature). Subscribing to messages is done by specifying a topic filter. Wildcards are also permitted (+ for one level and # for multiple levels). The message format is not fixed, which means that a JSON string or any data structure can be transmitted.

With the “MQTT Client SL” library, messages can be sent from a CODESYS controller to an MQTT broker, and messages can be subscribed to based on topics.

The “MQTT Client SL” package contains the following components:

• MQTT Client SL library with the following function blocks:

  • MQTTClient FB for establishing an MQTT link

  • MQTTPublish FB for sending messages

  • MQTTSubscribe FB for subscribing to messages

• Sample project “MQTT Client SL Example.project” with a visualization for sending and receiving messages

• Description of the function blocks (CHM help file)

• Data sheet (German/English)

Supported functions¶

• Publishing and subscription of messages based on MQTT V3.1.1 and MQTT V5.0

• TLS encryption

• Client certificates (transfer of a certificate handle)

• Quality of Service: 0, 1, and 2 (QoS0, QoS1, QoS2) for the last will, publisher, and subscriber

• Data type “Topics”: WSTRING

• Maximum size of a topic: 1024

• The maximum package size and payload size can be configured by means of a parameter list.

• Multitasking and multicore support (MQTTClient, MQTTPublish, and MQTTSubscribe can each be run on different tasks or CPU cores.)

• Last will messages (QoS0, QoS1, QoS2)

• Wildcards (# and +)

• MQTT over WebSocket

Supported MQTT V5 functions¶

• Session expiry: see MQTTConnectProperties.udiSessionExpiryInterval

• Message expiry: see MQTTPublishProperties.udiMessageExpiryInterval and MQTTWillProperties.udiMessageExpiryInterval

• Reason codes: The reason code of the last response is set to the output MQTTClient.eReaonCode

• Reason strings: see MQTTConnackProperties.wsReasonString and

• Server disconnect: The server can send a DISCONNECT packet to the client. The reason code will be set to MQTTClient.eReaonCode

• Payload format and content type: see MQTTPublishProperties.bPayloadFormatIndicator, MQTTWillProperties.bPayloadFormatIndicator, MQTTPublishProperties.wsContentType and MQTTWillProperties.wsContentType

• Request / Response: see MQTTPublishProperties.wsResponseTopic and MQTTWillProperties.wsResponseTopic

• Shared Subscriptions: A Shared Subscription is identified using a special style of Topic Filter. The format of this filter is: $share/{ShareName}/{filter}

• Subscription ID: see MQTTSubscribeProperties.udiSubscriptionIdentifier

• Topic Alias: see MQTTPublishProperties.uiTopicAlias

• Flow control: see MQTTConnackProperties.uiReceiveMaximum and MQTTConnectProperties.uiReceiveMaximum

• User properties: see MQTTConnectProperties.userProperties, MQTTConnackProperties.userProperties, MQTTConnectProperties.userProperties, MQTTPublishProperties.userProperties, MQTTSubscribeProperties.userProperties and MQTTWillProperties.userProperties

• Maximum Packet Size: see MQTTConnectProperties.udiMaximumPacketSize, MQTTConnackProperties.udiMaximumPacketSize

• Optional Server feature availability: see MQTTConnackProperties.bMaximumQoS, MQTTConnackProperties.bRetainAvailable, MQTTConnackProperties.bWildcardSubscriptionAvailable, MQTTConnackProperties.bSubscriptionIdentifierAvailable, MQTTConnackProperties.bSharedSubscriptionAvailable

• Enhanced authentication: see MQTTConnectProperties, MQTTConnackProperties and MQTTAuthProperties

• Subscription options: see MQTTSubscribeProperties.xNoLocalOption, MQTTSubscribeProperties.xRetainAsPublished and MQTTSubscribeProperties.eRetainHandling,

• Will delay: see MQTTWillProperties.udiWillDelayInterval

• Server Keep Alive: see MQTTConnackProperties.uiServerKeepAlive

• Assigned ClientID: see MQTTConnackProperties.wsAssignedClientIdentifier

• Server reference: see MQTTConnackProperties.wsServerReference

Contents:¶

Indices and tables¶